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25. Accessing Files 



The I. isp Miichinc can access files on a variety of remtHe file servers, which are typically (but 
not necessarily) accessed through the Chaosnct, as well as accessing files on the Lisp Machine 
itself, if the machine has its own file system. You are not allowed to refer to files without first 
logging in, and you may also need to specify a username and password for the host on which tJie 
file is stored; sec page 801. 

The way to read or write a file's contents is to open the file to get an input or output stream, 
use the standard stream I/O functions or operations described in chapters 22 and 23, and then 
close the stream. The first section of this chapter tells how to open and close Uic stream. The 
rest of the chapter describes things specific to files such as deleting and renaming, finding out the 
true name of tlie file that has been opened, and listing a directory. 

Files are named with pathnames. There is much to know about pathnames aside from 
accessing files with tJiem; all Uiis is described in die previous chapter. 

Many functions in this chapter take an argument called file which is intended to specify a file 
to be operated on. This argument may be given as a pathname (which is defaulted), a namcstring 
(which is parsed into a patlmamc and tlicn defaulted), or a stream open to a file (the same file is 
used). 

25.1 Opcninj; and Closing File Streams 

with-open-f He {stream file options...) body... Macro 

Hvaluatcs the body fomis with the variable stream bound to a stream that reads or writes 
the file named by tlie value affile. The options forms evaluate to tlic file-opening options 
to be used; sec page 582. 

When control leaves tlic body, cither normally or abnormally (via throw), the file is 
closed. If a new output file is being written and control leaves abnormally, the file is 
aborted and it is as if it were never written. Because it always closes die file, even when 
an error exit is taken, with -open -file is preferred over open. Opening a large number 
of files and forgetting to close them tends to break some remote file servers, ITS's for 
example. 

If an error occurs in opening the file, the result depends on the values of the error 
option, the if-exists option, and the if- does- not- exist option. An error may be signaled 
(and possibly corrected with a new pathname), or stream may be bound to a condition 
object or even nil. 

wlth-open-fHe-case {stream file options...) clauses... Macro 

Ihis opens and closes the file like with -open -file, but what happens afterward is 
determined by clauses that are like the clauses of a condition -case (page 702). Each 
clause begins with a condition name or a list of condition names and is executed if open 
signals a condition that possesses any of those names. A clause beginning with the symbol 
:no -error is executed if the file is opened successflilly. This would be where the reading 
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or writing of the file would be done. 
Hxample: 

(with-open-file-case (stream (send generic-pathname 

: source-pathname) ) 
(sys:remote-network-error (format t "~&Host down.")) 
(fs:f ile-not-found (format t "~&(New file)")) 
(:no-error (setq list (read stream)))) 

fne-retry-new-pathname {patlmamc-var comiilkm-mimes...) body.,. Macro 

f ile-retry-new-pathname-lf Macro 

conJ-forni {pathname- var condition-names...) body... 
file-retry-new-pathname executes body. If body does not signal any of the conditions in 
condition-names, body\ values arc simply returned. If any of condition-names is signaled, 
file-retry-new-pathname reads a new patJiname, setq's pathname- var to it, and executes 
body again. 

The user can type End instead of a patJinamc if he wishes to let tlic condition be handled 
by the debugger. 

file -retry -new -path name -if is similar, but tlic conditions are handled only if cond-fomi's 
value is non-nil. 

For an example, sec the example of die following macro. 

w1th-open-fne-petry ^/^cro 

(stream {pathname-var condition-names...) options...) body... 
IJke with -open -file inside of a file-retry-new-pathname. If an error occurs while 
opening tlie file and it has one of the specified condition-names, a new paUmame is read, 
tlie variable pathname-var is setq'd to it, and another attempt is made to open a file with 
the newly specified name. Example: 

(with-open-file-retry (instream (infile fs:f ile-not-found) ) 

infile should be a variable whose value is a patliname or namcstring. The example is 
equivalent to 

(file-retry-new-pathname (infile fs :f i le-not-found) 
(with-open-f ile (instream infile) 
...)) 

w1th-open-f ne-seapch j^f^cro 

Opens a file, trying various patlinames until one of them succeeds. The pathnames U-ied 
differ only in their type components. For example, load uses tliis macro to search for 
eitiicr a compiled file or a source file. 'ITie calling sequence looks like 
(with-open-f i le- search 

(streamvar (operation defaults auto-retry) 

types- and- pathname options, . . ) 
body, . . ) 



PS:<L.MAN>FII.RS.TEXT.24 8-JUN-84 



Opening and Closing l"ilc Slrc.ims 582 I isp Maciiinc Manual 



with -open -file-search tries opening various files until one succeeds; then binds strcamvar 
to the stream and executes Ixniy, closing the stream on exit. The values of body arc 
returned. 

types-ami- patlmame specifies which files to open. It should be a form which evaluates to 
two values, the first being a list of types xo try and Uie second being a pathname called 
ihc base pathname. Kach pathname to try is made by merging the base pathname with 
the defaults dcJliuUs and one of the types. Ihe types may be strings or canonical type 
keywords (see section 24.2.3, page 551). 

options are forms whose values should be alternating to keywords and values, which arc 
passed to open each time. 

if all the names to be tried fail, a fs:multiple-file-not-found error is signaled, operation 
is provided just so that the :operation operation on the condition object can return it. 
Usually the value given for operation should be iJic user-level function for which tlic 
with -open -file-search is being done. 

If auto-retry is non-nil, an error causes Uic user to be prompted for a new base patlmame. 
I he entire set of types specified is tried anew with the new pathname. 

open file &rcst options 

Returns a stream that is connected to die specified file. Unlike Maclisp, the open 
function creates streams only for files\ streams of other kinds arc created by other 
functions. '\\\q file and options arguments are tlie siimc as in with -open -file; sec above. 

When tJic caller is finished with the stream, it should close the file by using the :close 
operation or the close function. The with -open -file special form docs this automatically 
and so is usually preferred, open should only be used when the control structure of the 
program necessitates opening and closing of a file in some way more complex than the 
simple way provided by with -open -file. Any program that uses open should set up 
unwind -protect handlers (sec page 82) to close its files in the event of an abnormal exit. 

close streatn &optional option 

Ihe close fimction simply sends tlie :close message to stream. If option is :abort for a 
file output stream, the file is discarded. 

c11:c1ose stream &key abort 

The Common Lisp version of close is the same as close except for its calling convention. 
If abort is non-nil for a file output stream, the file is discarded. 

fsrclose-all-flles 

Closes all open files. This is useful when a program has run wild opening files and not 
closing tlicm. It closes all the files in -.abort mode (see page 464), which means that files 
open for output are deleted. Using this function is dangerous, because you may close 
files out from under various programs like Zmacs and ZMail; only use it if you have to 
and if you feel that you know what you're doing. 
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The options used when opening a file are normally allernaling keywords and values, like any 
oilier function ihat takes keyword arguments. In addition, for compatibility with the Maclisp 
open function, if only a single option is specified it is eitlier a keyword or a list of keywords (not 
alternating with values). 

The file-opening options control things like whether the stream is for input from a existing file 
or output to a new file, whether the file is text or binary, etc. 

The following keyword arguments are standardly recognized; additional keywords can be 
implemented by particular file system hosts. 

direction Controls which direction of 1/0 can be done on the resulting stream. The 

possible values are :input (the default), :output, nil, :probe. :probe -directory 
and :probe-link. The first two should be self-explanatory, nil or :probe means 
that tliis is a "probe" opening; no data are to be transferred, tJie file is being 
opened only to verify its existence or access its properties. The stream created in 
this case does not permit any I/O. nil and :probe differ in causing different 
defiuilts for the argument if- does- not- exist. If tliat argument is specified explicitly, 
nil and :probe arc equivalent. 

:probe-directory is used to sec whether a directory exists. If the directory 
specified for tJie file to be opened is found, then tlic open completes (returning a 
non-I/0 stream) as if the specified file existed whether it really exists or not. 

:probe-link is used to find out the truenamc of a link. If the file specified exists 
as a link, then the open completes returning a non-1/0 stream which describes 
tlic link itself ratJier tlian tlic file linked to. If the file exists and is not a link, 
the open also completes for it as with any probe. 

Common Lisp defines tlie value :io for tliis argument, requesting a stream that 
can do input and output, but no file system supported by the Lisp Machine has 
tliis capability. 

characters Hie possible values are t (the default), nil, which means that the file is a binary 

file, and :default, which means that the file system should decide whether the file 
contains characters or binary data and open it in tlie appropriate mode. 

byte-size The possible values arc nil (the default), a number, which is the number of bits 

per byte, and :default. which means tliat the file system should choose the byte 
size based on attributes of the file. If the file is being opened as characters, nil 
selects die appropriate system-dependent byte size for text files; it is usually not 
useful to use a different byte size. If the file is being opened as binary, nil selects 
the default byte size of 16 bits. 

element-type lliis is the Common Lisp way to specify what kind of objects the stream wants to 
read or write. This combines tlie effect of the characters and byte-size arguments. 
The value is a type specifier; it must be one of the following: 

string -char Read or write characters as usual. ITie default. 

character Read or write characters, dealing with characters that are more 
than 8 bits. You can succeed in writing out any sequence of 
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characicr Dbjccts and reading it back, but the file does not look 
anything like a text file. 

(unsigned -byte /;) 

Read or write //-bit bytes. Like chomctcrs = nil, byte-size = n. 



unsigned -byte 
(signed -byte//) 

signed -byte 
(mod //) 
:default 



Similar, but uses the byte size tliat the file was originally written 
with. This is tlie same as cluiraclers = nil, byte-size - :default. 

Read or write //-bit bytes, sign-extending on input, luich byte 
read from the file is sign-extended so tJiat its most significant bit 
serves as a sign bit. 

Similar, but uses the byte si/.e lliat tiic file was originally written 
with. 

Ijke unsigned -byte for a big enough byte size to hold all 
numbers less than //. bit is also accepted, and means (mod 2). 



Is allowed, even though it is not a type specifier. It is the same 
as using :default as the value of characters. 

if-exists For output opens, if-exists specifies what to do if a file with the specified name 

already exists. There arc several values you can use: 

:new-version Create a new version. This makes sense only when die pathname 
has :newest as its version, and it is the default in that case. 

:supersede Make a new file which, when closed, replaces the old one. 

:overwrite Write over die data of the existing file, stiirting at the beginning, 
and set the file's length to the length of the newly written data. 

:truncate Like :overwrite except that it discards the old contents of the file 

immediately, making it empty except for what is written into it 
this time. 

:append Add new data onto the existing file at the end. 

:rename Rename the existing file and then create a new one. 

:renam€-and -delete 

Rename the existing file, create a new one, and delete the old file 
when the new one is closed. 



:error 



nil 



Signal an error (fs:file-already-exists). This is die default when 
the patliname's version is not :newest. Hie ftirther handling of 
the error is controlled by the error argument. 

Return nil from open in this case. The error argument is 
irrelevant in this case. 



if- does- not- exist 



Specifics what to do when the file requested does not exist. There arc three 
allowed values: 
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error 



:subnut 

deleted 

temporary 
preserve- dates 
flavor 

link- to 
submit 

estimated- size 



:create 



:error 



nil 



Create a file. This is the default for output opens, except when 
ij-exisis is :append, :overwrite or :truncate. This silly exception 
is part of the Common Lisp specifications. 

Signal an error. This is the default for input opens, and also for 
output opens when if-exisis is :append, :overwrite or :truncate. 
The further handling of the error is controlled by the error 
argument. 

he 



Return nil from open. This is the default for :probe opens 
error argument is irrelevant in this case. 

Specifies what to do if an error is signaled for any reason. (Note that the values 
of tlie if-exisfs and if docs- not- exist arguments control whether an error is signaled 
in certain circumstances.) Ihe possible values are t (the default). :reprompt and 
nil. t means that nothing special is done, so the error invokes the debugger if die 
caller docs not handle it. nil means that the condition object should be returned 
as the value of open. :reprompt means that a new file name should be read and' 
opened. 

Any caller which need not know reliably which file was ultimately opened might 
as well specify :reprompt for this argument. Callers which need to know if a 
different file is substituted should never specify :reprompt; they may use with- 
open- file -retry or file -retry -new -pathname (sec page 581) if they wish to 
pennit an alternative file name to be substituted. 

If specified as t when opening a file for output, the file is submitted as a batch 
job if it is closed normally. The default is nil. You must specify :direction 
:output as well. 

Hie default is nil. If t is specified, and the file system has the concept of deleted 
but not expunged files, it is possible to open a deleted file. Otherwise deleted 
files are invisible. 

If t is specified, the file is marked as temporary, if the file system has that 
concept. The default is nil. 

If t is specified, the file's reference and modification dates are not updated. The 
default is nil. 

This controls the kind of file to be opened. The default is nil, a normal file. 
Other possible values are :directory and :link. Only certain file systems recognize 
this keyword. 

When creating a file with flavor :link, this argument must be specified; its value is 
a pathname or namestring that becomes the target of the link. 

Ilie value can be eitlier nil (the default) or t. If the value is t, and the 
rdirection is :output, the resulting file will be submitted as a batch job. 
Currently, this option is implemented only for Twenex and VMS. 

The value may be nil (the default), which means there is no estimated size, or a 
number of bytes. Some file systems use this to optimize disk allocation. 
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physical-volume The value may be nil (the dcfaull), or a string that is tlie name of a physical 
volume on which ihe file is lo be stored. This is not meaningful for all file 
systems. 

logical-volume The value may be nil (the deOiult), or a string tJiat is the name of a logical 
volume on which the file is to be stored. This is not meaningful for all file 
systems. 

super-image The value may be nil (the default), or t, which disables the special treatment of 
ruboul in ASCI! files. Normally, rubout is an escape which causes the following 
character to be interpreted specially, allowing all characters from through 376 
((Ktal) to be stored. This applies to ASCII file servers only. 

raw The value may be nil (the default), or t, which disables all character set 

translation in ASCII files. This applies to ASCII file servers only. 

In the Maclisp compatibility mode, there is only one option, and it is cither a symbol or a 
list of symbols. These symbols are recognized no matter what package tJiey are in, since Maclisp 
docs not have packages. The following symbols are recognized: 

in, read Select opening for input (the default). 

out, write, print 

Select opening for output; a new file is to be created. 

binary, fixnum Select binary mode; otherwise character mode is used. Note tliat fixnum mode 
uses 16-bit binary words and is not compatible with Maclisp fixnum mode, which 
uses 36-bit words. On tlic PDF-10, fixnum files arc stored with two 16-bit words 
per PDP-10 word, left-justified and in F1)P-10 byte order. 

character, ascii 

Tlic opposite of fixnum. This is the default. 

single, block Ignored for compatibility with tlie Maclisp open function. 

byte-size Must be followed by a number in the options list, and must be used in 

combination with fixnum. ITie number is the number of bits per byte, which can 
be from 1 to 16. On a PDP-10 file server these bytes will be packed into words 
in the standard way defined by the ILDB instruction. The :tyi stream operation 
will (of course) return die bytes one at a time. 

probe, error, noerror, raw, super- image, deleted, temporary 

These are not available in Maclisp. The corresponding keywords in the normal 
form of file-opening options are preferred over these. 
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25.2 I1le Stream Operations 

The following functions and operations may be used on file streams, in addition to the 
normal I/O operations which work on all streams. Note that several of these operations arc useful 
with file streams that have been closed. Some operations use pathnames; refer to chapter 24, 
page 545 for an explanation of pathnames. 

file-length filc-strcam 

Returns the length of the file open on filc-sircam, in terms of the units in which I/O is 
being done on that stream. (A stream is needed, rather tlian just a pathname, in order to 
specify the units.) 

f 1le-pos1t1on filc-strcam &optional new-position 

With one argument, returns the current position in the file of filc-strcam, using tlic 
:read -pointer stream operation. It may return nil meaning that the position cannot be 
determined. In fad, it always returns nil for a stream open in character mode and not at 
the beginning of the file. 

With two arguments, sets the position using the :set- pointer stream operation, if possible, 
and returns t if the setting was possible and nil if not. You can specify :start as the new- 
position to position to tlie beginning of tlie file, or :end to position to the end. 

: pathname Operation on file streams 

Returns the patliname that was opened to get tliis stream. This may not be identical to 
tlie argument to open, since missing components will have been filled in from defaults. 
The patJmame may have been replaced wholesale if an error occurred in tlie attempt to 
open die original pathname. 

: t r u e n ame Operation on file streams 

Returns the patliname of the file actually open on this stream. This can be different from 
what ipathname returns because of file links, logical devices, mapping of version :newest 
to a particular version number, etc. For an output stream the truename is not meaningful 
until after the stream has been closed, at least when the file server is an ITS. 

: generic-pathname Operation on file streams 

Returns tlie generic pathname of the pathname that was opened to get this stream. 
Normally this is the same as tlie result of sending tlie :generic- pathname message to the 
value of the :pathname operation on the stream; however, it does special tilings when 
tlie Lisp system is bootstrapping itself. 

: qf as 1 p Operation on file streams 

Returns t if the file has a magic flag at the front that says it is a QFASL file, nil if it is 
an ordinary file. 

: 1 e n g t h Operation on file streams 

Returns the length of the file, in bytes or characters. For text files on ASCII file servers, 

this is the number of ASCII characters, not Lisp Machine characters. The numbers are 

different because of character-set translation; see section 25.8, page 607 for a full 

• explanation. For an output stream the length is not meaningful until after the stream has 
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been closed, al leasl when Uk file server is an I'l'S. 

:creat1on-date Operation on file streams 

Rciurns the creation date of the file, as a number that is a luiiversal time. Sec the 
chapter on the time package (chapter 34, page 776). 

! i n f Operation on file streams 

Returns a cons of the file's imcname and its creation date. This can be used to tell if Uic 
file has been modified between two open's, l-'or an output stream the information is not 
guaranteed to be correct initil after the stream has been closed. 

: properties &optional (erroi-p t) Operation on file streams 

This returns two values: a property list (like an element of the list returned by 
fs:directory-list), and a list of the settable properties. See the section on standard file 
properties (section 25.6, page 598) for a description of tlie ones that may possible found 
in tlic list. 

:set-byte-s1ze new*- byte- size Operation on file streams 

rhis is only allowed on binary file streams. 'I'he byte size can be changed to any number 
of bits from 1 to 16. 

: delete &optional {erroi^p t) Operation on file streams 

Deletes tJie file open on tliis stream. For the meaning of error^p, sec tlic deletef 
function. 1 he file doesn't really go away until tlie stream is closed, 

: undelete &optional {error-p X) Operation on file streams 

If you have used Uic :deleted option in open to open a deleted file, this operation 
undeletes tlie file. 

: rename new-name &optional {error-p t) Operation on file streams 

Renames the file open on this stream. For the meaning of error-p, see the renanfief 
function. 

Pile output streams implement the :finish and :force- output operations. 

25.3 Manipulating Files 

This section describes functions for doing things to files aside from reading or writing their 
contents. 

true name object 

Returns the tnienamc of the file specified somehow by object. If object is a plausible 
stream, it is asked for the truename with the :truename operation. Otherwise, object is 
converted to a pathname and that pathname is opened to get its file's truename. 
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delete -file jile &key {cnvi-pX) query? 

deletef file Aoplional {cnvi-p\) query? 

lioth delete Lhc specified file. The two functions differ in accepting keyword arguments 
versus positional arguments, file may contain wildcard characters, in which case multiple 
files are deleted. 

If query? is non-nil, the user is queried about each file (whether there are wildcards or 
not). Only the files that the user confirms are <ictually deleted. 

If error p is t, then if an error occurs it is signaled as a Lisp error. If error p is nil and 
an error occurs, the error message is returned as a condition object. Otherwise, the value 
is a list of elements, one for each file considered. The car of each element is the 
truenamc of the file, and the cadr is non-nil if the file was actually deleted (it is always t 
unless querying was done). 

undelete-f He file &key {error-pi) query? 

undeletef file &optional {error-pi) query? 

Both undelete tlic specified file. Wildcards are allowed, just as in deletef. llic rest of 
tlic calling conventions arc the same as well, lhc two functions differ in taking keyword 
arguments versus positional arguments. 

Not all file systems support undeletion, and if it is not supported on tJie one you are 
using, it gets an error or returns a string according to error p. To find out whether a 
particular file system supports tJiis, send tJic :undeletable-p operation to a pathname. If 
it returns t, the file system of that pathname supports undeletion. 

re name-file file ne\v-name &key {error pt) query? 

re name f file new name &optional {error pi) query? 

Both rename tlie specified file to new-name (a pathname or string). The two functions 
differ in taking keyword arguments versus positional arguments, file may contain 
wildcards, in which case multiple files are renamed. Each file's new name is produced by 
passing new-name to merge -pathname-defaults with the file's truename as the defaults. 
Therefore, new-name should be a string in this case. 

If query? is non-nil, tlie user is queried about each file (whether there are wildcards or 
not). Only tlie files that the user confinns arc actually renamed. 

If error p is t, then if an error occurs it is signaled as a. Lisp error. If error p is nil and 
an error occurs, the error message is returned as a condition object. Otlierwise, the value 
is a list of elements, one for each file considered. The car of each element is the original 
truename of the file, the cadr is the name it was to be renamed to, and the caddr is 
non-nil if the file was renamed. The caddr is nil if the user was queried and said no. 

copy-file file newname &key {errorX) {copy- creation- date \) {copy- author i) report-stream 
{create-directories-.quer'/) {characters -.cHefaiili) {byte-size .deiauW) 
Copies the file specified by file to the name new-name. 
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characters and bylc-sizc specify what mode of 1/0 to use to transfer the data, characters 
can be 



t 

nil 

.ask 



to specify character input and output, 
for binary input and output, 
meaning ask the user which one 



:maybe-ask meaning ask if it is not possible to tell with certainty which method is 
best. 



:default 



meaning to guess as well as possible automatically. 



If binary transfer is done, byte-size specifies tlie byte size to use: :default means to ask 
the file system for tlie byte size that the old file is stored in, just as it does in open. 

copy-author and copy- creation- date say whether to set those properties of the new file to be 
the same as those of Uie old file. If a property is not copied, it is set to your login name 
or tlie current date and time. 

report- St ream, if non-nil, is a stream on which a message should be printed describing the 
file copied, where it is copied to, and which mode was used. 

create- directories says what to do if tlie output filename specifies a directory that does not 
exist. It can be t meaning create the directory, nil meaning treat it as an error, or -.query 
meaning ask tJie user which one to do. llie default is :query. 

error, if nil, means that if an error happens then this funcdon should just return an error 
indication. 

If the pathname to copy from contains wildcards, multiple files are copied. The new 
name for each file is obtained by merging newmme (parsed into a pathname) with that 
file's truenamc as a default. ITie mode of copy is determined for each file individually, 
and each copy is reported on the report-stream if there is one. If error is nil, an error in 
copying one file does not prevent the others from being copied. 

There arc four values. If wildcards were used, each value is a list with one element 
describing each file that matched; otherwise, each value describes the single file specified 
(though the value may be a list anyway). ITie values, for each file, are: 

output-file The defaulted pathname to be opened for output in copying this file. 

ITie trucname of the file copied 



iruename 
outcome 

mode 



The truename of the new file. If the file was successfully copied. A 
condition object, if there was an error and error was nil. nil if the user 
was asked whether to copy this file and said no. 

A Common Lisp type descriptor such as string -char or (unsigned -byte 
8) saying how the file was copied. 
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probe-fHe file 

probef file 

Returns nil if there is no file named file\ otherwise rctin-ns a pathname that is the true 
name of the file, which can be diflcrent from file because of file links, version numbers, 
etc. lf//7<' is a stream, this fimction cannot return nil. 

Any problem in opening tlie file except for fs:file-not-found signals an error. 

probef is the Maclisp name; probe-file is the Common Lisp name. 

file-write- date file 

Returns the creation date/time v>{ file, as a universal time. 

file-author file 

Returns the name of the author o^ file (the user who wrote it), as a string. 

viewf .///f (feoptional (ow//?///-5/m/m *standard-output*) leader 

Copies the contents of the specified file, opened in character mode, onto output-stream. 
Normally this has the effect of printing the file on the terminal, leader is passed along to 
stream -copy- until -eof (sec page 457). 

fs:create-l1nk link-name link-fo &key (errort) 

Creates a link named link-name which points to a file named link-fo. An error happens if 
tlie host specified in link-name docs not support links, or for any of tlie usual problems 
that can happen in creating a file. 

25.3.1 Loading Files 

To load a file is to read tlirough tlie file, evaluating each form in it. Programs are typically 
stored in files; tlic expressions in the file arc mostly special forms such as defun and defvar 
which define Uic functions and variables of the program. 

Loading a compiled (or QFASL) file is similar, except that the file does not contain text but 
rather pre-digested expressions created by tlie compiler which can be loaded more quickly. 

Tliese functions are for loading single files. There is a system for keeping track of programs 
which consist of more than one file; for fijrther information refer to chapter 28, page 660. 

load file &key verbose print {if- does- not- exist i) set-default- pathname package 

Loads Uie specified file into the Lisp environment. \i file is a stream, load reads from it; 
otherwise file is defaulted from the default pathname defaults and the result specifies a file 
to be opened. If the file is a QFASL file, fasload is used; otherwise readfile is used. If 
file specifies a name but no type, load looks first for tlie canonical type :qfasl and then 
for the canonical type :lisp. 

Normally the file is read into tlie package specified in its attribute list, but if package is 
supplied tlien the file is read in that package. If package is nil and verbose is nil, load 
prints a message saying what file is being loaded and what package is being used, verbose 
defaults to tlie value of * load -verbose*. 
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If if- (iocs- not- ex isi is nil, load just iciurns nil if no file with the specified name exists. 
F,iTor conditions other tJian fs:file- not-found are not handled by this option. 

If a file is loaded, load returns the file's truenamc. 

If print is nt)n-nil, the value of each expression evaluated from tlie file is printed on 
*standard-output*. 

pathname is defaulted from the default pathname defaults. If sci-defaull-palhnamc is non- 
nil, the pathname defaults are set to the name of tJie file loaded. The default for set- 
Jcfault- pathname is t. 

load used to be called with a diflcrcnt calling sequence: 
(load pathname pkg nonexistent-ok 
donl-set-defauU) 
11iis calling sequence is detected and still works, but it is obsolete. 

•load- verbose* Variable 

Is tlie default value for the verbose argument to load. 

peadflle file &optional pkg no-msg-p 

readfile is the version of load for text files. It reads and evaluates each expression in the 
file. As with load, pkg can specify what package to read tlie file into. Unless no-msg-p is 
t, a message is printed indicating what file is being read into what package. 

fas load file &optional pkg no-msg-p 

fasload is the version of load for QFASL files. It defines functions and performs other 
actions as directed by tlie specifications inserted in the file by tlie compiler. As with load, 
pkg can specify what package to read the file into. Unless no-msg-p is t, a message is 
printed indicating what file is being read into what package. 

25.4 Pathname Operations That Access Files 

Here are the operations that access files. Many accept an argument error or error^p which 
specifies whether to signal an error or to return a condition instance, if the file cannot be 
accessed. For these arguments, nil and non-nil are the only significant values. :reprompt has no 
special meaning as a value. That value when passed to one of the file accessing functions (open, 
deletef, etc.) has its special significance at a higher level, 

: true name Operation onipaihname 

Returns a pathname object describing the exact name of the file specified by the pathname 
the object is sent to. 

This may be different from the original pathname. For example, the original pathname 
may have :newest as the version, but the truename always has a number as the version if 
the file system supports versions. 
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:open paihnanw &icst opfions Opera lion on pathname 

Opens a stream for the file named by the pathname. The argument paihnamc is what the 
.pathname operation on the resulting stream should return. When a logical paihnamc is 
opened, pathname is that logical pathname, but self is its translated patlinamc. 

options is a list of alternating keywords and values, as wi)uld be passed to open. The old 
style of open keywords arc not allowed; when tliey are used with open, open converts 
them to the new style before sending the :open message. 

: delete &optional (error-p t) * 0/;m///V;/; o// pathname 

: undelete &optional {envt^p t) Operation on pathname 

Respectively delete or undelete the file specified by the patlinamc. 

All file systems support :delete but not all support :undeiete. 

If error-p is nil, problems such as nonexistent files cause a string describing tlic problem 
to be returned. Otherwise, tlicy signal an error. 

:unde1etab1e*p Operation on pathname 

Returns t if this patlinamc is for a file system which allows deletion to be undone. Such 
pathnames support tlic :undelete and :expunge operations. 

: rename new-name &optional {error-p t) Operation on pathname 

Renames tlic file specified by the pathname, new-name, a string or pathname, specifies 
the name to rename to. If it is a string, it is parsed using self as tlic defaults. 

if error-p is nil, problems such as nonexistent files cause a string describing the problem 
to be returned. Otherwise, they signal an error. 

: c omp lete-strlng string options Operation on pathname 

Attempts to complete the filename string, returning the results. This operation is used by 
the function fs:complete- pathname (see page 602). The patliname the message is sent to 
is used for defaults, options is a list whose elements may include :deleted, :read (file is 
for input), :write (it's for output), :old (only existing files allowed), or :new-ok (new files 
are allowed too). 

ITiere are two values: a string, which is die completion as far as possible, and a flag, 
which can be :old, :new or nil. :old says that the returned su*ing names an existing file, 
:new says tliat the returned string is no file but some completion was done, nil says that 
no completion was possible. 

change ~ properties error-p &rest properties Operation on pathname 

Changes the properties of the file specified by the pathname, properties should be an 
alternating list of property names and values. 
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: directory- list opiums Operation on jpaXhname 

Pcrlbrms the WDik of (fs:directory-list ihis-palhnanic options...). 

: properties Opcmtion on pathname 

Returns a property list (in tlie form of a directory-hsl element) and a list of sellable 
properties. See section 25.6, page 598 for more infomiation on file properties. 

: wildcard-map function plistp dii^list-options &rest args Operation on paXhname 

Maps function over all the files specified by this pathname (which may contain wildcards). 
I'ach umc function is called, its first argument is a pathname with no wildcards, or else a 
dircclory-list clement (whose car is a pathname and whose cdr contains property names 
and values). The elements of args are given to function as additional arguments. 

plistp says whether function's first argument should be a directory-list clement or just a 
pathname, t specifics a directory-lisi element. That provides more information, but it 
makes it necessary to do extra work if the specified patlmamc does not contain wildcards. 

dir-list-options is passed to fs:directory-list. You can use tliis to get deleted files 
mentioned in tlic list, for example. 

The remaining file-access operations are defined only on certain file systems. 

: expunge &key {error t) Operation on ^aihnavne 

Expunges tlie directory specified by the host, device and directory components of the 
pathname. 

The argument error says whether to signal an error if the directory does not exist, nil 
means just return a string instead. 

:create-directory &key {error t) Operation on \ia\\\r\amQ 

Creates the directory specified in this pathname. 

: remote-connect &key {error t) access Operation on pathname 

Performs the work of fs: remote -connect with the same arguments on this pathname's 
host. 



25.5 File Attribute Lists 

Any text file can contain an attribute list that specifies several attributes of the file. The above 
loading functions, tlic compiler, and the editor look at this property list. Attribute lists are 
especially useful in program source files, i.e. a file that is intended to be loaded (or compiled and 
then loaded). QFASL files also contain attribute lists, copied from their source files. 

If the first non-blank line in a text file contains the three characters '-♦-', some text, and '- 
♦ -' again, the text is recognized as the file's attribute list. Each attribute consists of the attribute 
name, a colon, and the attribute value. If there is more than one attribute they are separated by 
semicolons. An example of such an attribute list is: 

; -♦- Mode:Lisp; Package: Cellophane ; Base:10 -•- 
This defines three attributes: mode, package, and base. The initial semicolon makes the line 



I'S:<L.MAN>F1LES.TEXT.24 8-JUN-84 



isp Machine Manual 595 lilc Aitribiile I .isls 



look like a commeni rather than a l.isp expression. Another example is: 

.c Part of the Lisp Machine manual. -*- Mode:Bolio -*- 

An attribute name is made up of letters, numbers, and otherwise-undefined punctuation 
characters such as hyphens. An attribute value can be such a name, or a decimal number, or 
several such items separated by commas. Spaces may be used freely to separate tokens. Upper 
and lower-case letters are not distinguished. There is no quoting convention for special characters 
such as colons and semicolons. 

If tlie attribute list text contains no colons, it is an old Hmacs format, containing only tlie 
value of the Mode attribute. 

The file attribute list format actually has nothing to do with Lisp; it is just a convention for 
placing some infomiation into a file that is easy for a program to inteipret. The L:macs editor on 
the PI)P-10 knows how to interpret these attribute lists (primarily in order to look at the Mode 
attribute). 

The J Jsp Machine handles the attribute list stored in tJie file by parsing it into a Lisp data 
structure, a property list. Attribute names arc interpreted as Lisp symbols and are interned on the 
keyword package. Numbers are interpreted as Lisp fixnums and arc read in decimal. If a 
attribute value contains any commas, then tlie commas separate several expressions that are 
formed into a list. 

When a file is compiled, its attribute list data structure is stored in tlie QFASL file. It can 
be loaded back from the QFASL file as well. The representation in the QFASL file resembles 
notliing described here, but when the attribute list is extracted from tliere, tlie same Lisp data 
structure described above is obtained. 

When a file is edited, loaded, or compiled, its file attribute list is read in and tlie properties 
are stored on the property list of tlie generic pathname (see section 24.5, page 561) for that file, 
where they can be retrieved with the :get and :plist messages. This is done using the function 
fs:read-attribute-list, below. So the way you examine the properties of a file is usually to use 
messages to a pathname object that represents the generic pathname of a file. Note that there are 
other properties there, too. 

Here the attribute names with standard meanings: 

Mode The editor major mode to be used when editing this file. Tliis is typically the 

name of the language in which the file is written. The most common values are 
Lisp and Text. 

Package ITiis attribute specifies the package in which symbols in the file should be 

interned. 'ITie attribute may be either the name of a package, or a list that 
specifies both the package name and how to create the package if it does not 
exist. If it is a list, it should look like (name superpackage initial-size ...options...). 
See chapter 27, page 636 for more information about packages. 

Base 71ie number base in which the file is written (remember, it is always parsed in 

decimal). 1liis affects both *read-base* and *print-base*, since it is confusing 
to have the input and output bases be different. ITie most common values are 8 
and 10. 
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Readtable The value specifies ihe syntax (that is, the choice of leadtable) to use for reading 
i.isp objects from this file. The defined values are t or traditional for traditional 
I. isp Machine syntax, and cl or common-lisp for Common Lisp syntax. If you 
do not specify this option, the objects in tlie file are read using whatever 
readiable is current in the program that reads them. 

Lowercase If tlie attribute value is not nil, the file is written in lower-case letters and the 
editor docs not translate to upper case. (The editor does not translate to upper 
case by default unless the user enables l^lectric Shift Lock mode.) 

Fonts Lhe attribute value is a list of font names, separated by commas. The editor uses 

this for files that are to be displayed in a specific font, or contain multiple fonts. 
If this attribute is present, the file is actually stored in iJic file system with font- 
change indicators. A font-change indicator is an epsilon (i) followed by a digit or 
♦ . ni means to enter font /;. The previous font is saved on a stack and c* 
means to pop the stack, reunning to tlie previous font. If tlie file includes an 
epsilon as part of its contents, it is stored as ee. 

When expressions are read from such files, font-change indicators arc ignored, and 
t£ is treated as a single e. 

Backspace If tlic attribute value is not nil, Overstrike characters in the file should cause 
characters to overprint on each other, 'lhe dcfliult is to disallow overprinting and 
display Overstrike the way other special function keys are displayed. This default 
is to prevent tlic confusion that can be engendered by ovcrstmck text. 

Patch -File If tlie attribute value is not nil, the file is a patch file. When it is loaded the 
system will not complain about function redefinitions. In a patch file, tlie defvar 
special-form turns into defconst; tlius patch files always reinitialize variables. 
Patch files are usually created by special editor commands described in section 
28.8, page 672,, 

Cold -Load A non-nil value for tliis attribute identifies files that are part of tlie cold load, the 
core from which a new system version is built. Certain features that do not work 
in the cold load check this flag to give an error or a compiler warning if used in 
such files, so tliat the problem can be detected sooner. 

You are free to define additional file attributes of your own. However, to avoid accidental 
name conflicts, you should choose names that are diflxjrent from all the names above, and from 
any names likely to be defined by anybody else's programs. 

Tlic following functions are used to examine file attribute lists: 

fs:f1le-attPlbute-l1st pathname 

Returns the attribute list of the file specified by the pathname. This works on both text 
files and QFASL files. 
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f5:extract-attrllmte-1ist stream 

Returns tlie Jitributc list read from tiic specified stream, which should be pointing to the 
beginning of a file, 'i'his works on both text streams and QK'ASL file binary streams. 
After tlic attribute list is read, tlie stream's pointer is set back to tlie beginning of the file 
using the :selt-pointer file stream operation (see page 468). 

fs:read-attr1but©-l1st paihmme stream 

pathname shcMild be a patliname object {uot a string or namelist, but an actual patlmame); 
usually it is a generic patlmame (see section 24.5, page 561). stream should be a stream 
that has been opened and is pointing to tlie beginning of the file whose file attribute list 
is to be parsed. The attribute list is read from the stream and tlien corresponding 
properties are placed on tlie specified pathname. The attribute list is also returned. 

The fundamental way that programs in tlie Lisp Machine notice the presence of properties on 
a file's attribute list is by examining the property list in the generic pathname. However, tliere is 
another way tliat is more convenient for some applications. File attributes can cause special 
variables to be bound whenever Lisp expressions are being read from the file— when the file is 
being loaded, when it is being compiled, when it is being read from by the editor, and when its 
QFASL file is being loaded. This is how tlie Package and Base attributes work. You can also 
deal with attributes this way, by using the following fimction: 

fs:f ne-attr1bute-b1ndings pathname 

Returns values describing the special variables tliat should be bound before reading 
expressions from file pathname. It examines tlie property list of pathname and finds all 
those property names tliat have fs:file -attribute- bindings properties. Each such property 
name specifies a set of variables to bind and a set of values to which to bind tliem. This 
function returns two values, a list of all tlie variables and a list of all the corresponding 
values. Usually you use this function by calling it on a generic pathname that has had 
fs:read- attribute -list done on it, and then you use the two returned values as the first 
two arguments of a progv special form (see page 32). Inside the body of the progv the 
specified bindings will be in effect. 

pathname may be anything acceptable as the first argument of get. Usually it is a generic 
pathname. 

Of the standard attribute names, the following ones have fs:file-attribute-blndings, with 
tlie following effects. Package binds the variable package (see page 637) to the package. 
Base binds the variables * print -base* (see page 514) and * read -base* (see page 517) to 
the value. Readtable binds the variable readtable to a value computed from the 
specified attribute. Patch-file binds fs:this-is-a-patch-fjle to the value. Cold-load 
binds si: file -in -cold -load to the value. Fonts binds sl:read-discard-font-changes to t. 

Any properties whose names do not have fs:file-attribute-bindlngs properties are ignored 
completely. 

You can also add your own attribute names that affect bindings. If an indicator symbol 
has an fs:file-attrlbute-blndings property, the value of that property is a function that is 
called when a file witli a file attribute of tliat name is going to be read from. The 
fimction is given three arguments: the file pathname, the attribute name, and the 
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attribute value. It must return two values: a list of variables to be bound and a list of 
values to bind them to. The function for Uie Base keyword could have been defined by: 
(defun {:base file-attribute-bindings) (file ignore bse) 
(if (not (and (typep bse 'fixnum) 
(> bse 1) 
(< bse 37.))) 
(ferror 'fs:invalid-file-attrbute 

"File.~A has an illegal -*- Base:~D -*-" 
file bse)) 
(values (list 'base 'ibase) (list bse bse))) 

fs:extract-attr1bute-b1nd1ngs stream 

Returns two values: a list of variables, and a corresponding list of values to bind them 
to, giving tlie attribute bindings of the attribute list found on stream 

fs: 1nval1d-f lie-attribute (error) Condition 

An attribute in the file attribute list had a bad value. This is detected witliin fsifile- 
attribute-bindings. 

25.6 Accessing Directories 

To understand the ftmctions in this section, it- is vital to have read the chapter on pathnames. 
The jilespec argument in many of these functions may be a pathname or a namcstring; its name, 
type and version default to :wild. 

Ustf Jilespec 

Prints on 'standard -output* the names of the files that match filespec, and their sizes, 
creation dates, and other information that comes in the directory listing. 

fs: directory-! 1st Jilespec «&rcst options 

Finds all the files tliat match Jilespec and returns a list with one element for each file. 
Each element is a list whose car is the pathname of the file and whose cdr is a list of the 
properties of the file; tlius the element is a disembodied property list and get may be 
used to access the file's properties. The car of one element is nil; the properties in this 
clement are properties of the file system as a whole rather than of a specific file. 

Jilespec nomially contains wildcards, and the data returned describe all existing files that 
match it. If it contains no wildcards, it specifies a single file and only that file is 
described in the data that are returned. 

The options are keywords which modify the operation. The following options are currently 
defined: 

:noerror If a file-system error (such as no such directory) occurs during the 

operation, normally an error is signaled and the user is asked to supply a 
new pathname. However, if inoerror is specified dien, in the event of an 
error a condition object describing die error is returned as the result of 
fs:directory-list. This is identical to the :noerror option to open. 
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:deleted Tliis is for (ilc servers on which deletion is not permanent. It specifics 

that deleted (but not yet expunged) files are to be included in ihc 
directory listing. 

:sorted This requests that the directory list be sorted by filenames before it is 

returned. 

The properties that may appear in the list of propert\ lists returned by fs.directory-list 
are host-dependent to some extent. The following properties are those that are defined for 
both ITS and TOPS-20 file servers. This set of properties is likely to be extended or 
changed in the lliturc. 

:length- in "bytes 

The length of the file expressed in terms of the basic units in which it is 
written (characters in the case of a text file). 

:byte-size Ihc number of bits in one of those units. 

:length-in-blocks 

The Icngtli of the file in terms of the file system's unit of storage 
allocation. 

:block-size The number of bits in one of those units. 

:creation-date The date the file was created, as a universal time. Sec chapter 34, page 
776. 

:reference-date 

The most recent date on which the file was used, as a universal time or 
nil, meaning tlie file was never referenced. 

:modification-date 

The most recent date on which the file's contents were changed, as a 
universal time. 

:author ITie name of tlic person who created die file, as a string. 

:reader The name of the person who last read the file, as a string. 

mot -backed -up 

t if the file exists only on disk, nil if it has been backed up on magnetic 
tape. 

:directory t if this file is actually a directory. 

:temporary t if this file is temporary. 

ideleted t if this file is deleted. Deleted files are included in the directory list only 

if you specify tlie :deleted option. 

:dont-delete t indicates that the file is not allowed to be deleted. 

:dont-supersede 

t indicates that the file may not be superseded; that is, a file with the 
same name and higher version may not be created. 

:dont-reap t indicates that this file is not supposed to be deleted automatically for 
lack of use. 
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:dont-dump t indiciUcs lli;il this file is not supposed lo be dumped onto magnetic tape 
for backup purposes. 

:characters t indicates that tliis file contains ciiaractcrs (that is, text), nil indicates that 
the file contains binary datii. This property, rather than the file's byte 
si/c, should be used to decide whether it is a text file. 

:link-to if the file is a link, this property is a string containing the name tliat the 

link points to. 

:offline T if the file's contents arc not online. 

:incremental-dump- date 

The last time this file was dumped during an incremental dump (a 
universal time). 

:incremental-dump-tape 

The tape on which tlie last was saved in that incremental dump (a string). 

;complete-dump-date 

The last time tliis file was dumped during an full dump (a universal time). 

:complete-dump-tape 

The tape on which the last was saved in that full dump (a string). 

:generation- retention -count 

1 he number of files differing in version that are kept around. 

.default-generation-retention-count 

The generation-retention-count that a file ordinarily gets when it is created 
in this directory. 

:auto-expunge- interval 

The interval at which files are expunged from this directory, in seconds. 

:date-last-expunged 

'llic last (universal) time tliis directory was expunged, or nil. 

:account The account to which the file belongs, a string. 

:protection A system-dependent description of the protection of this file as a string. 

:physical-volume 

A string naming the physical volume on which the file is found. 

:volume-name 

A string naming the logical volume on which the file is found. 

:pack- number A string describing the pack on which this file is found. 

:disk-space-descriptlon 

A system-dependent description of the space usage on the file system. 
This usually appears in the plist that applies to the entire directory list. 

The element in the directory list that has nil instead of a file's pathname describes the 
directory as a whole. 
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:physical- volume-free -blocks 

This properly is an alisl in which each elemenl maps a physical volume 
name (a string) into a number, that is the number of free blocks on that 
volume. 

:settable- properties 

This property is a list of file property names ihai may be set. This 
information is provided in the directory list because it is different for 
different file systems. 

pathname This property is the pathname from which this directory list was made. 

:block-size This is the number of words in a block in this directory. It can be used 
to interpret the numbers of free blocks. 

fsidl rectory- 11 St -stream filespcc &rcst opfions 

This is like fs:directory-list but returns the information in a different fonn. Instead of 
returning the directory list all at once, it returns a special kind of stream which gives out 
one element of the directory list at a time. 

The directory list stream supports two operations: :entry and :close. :entry asks for the 
next element of tlie directory stream. :close closes any connection to a remote file server. 

The purpose of using fs:dlrectory-list-stream instead of fs:clirectory-llst is that, when 
communicating with a remote file server, the directory list stream can give you some of 
the information without waiting for it to all be transmitted and parsed. This is desirable 
if the directory is being printed on the console. 

directory fikspec 

Returns a list of pathnames (truenamcs) of the files in the directory specified by fikspec. 
Wildcards are allowed. 71iis is the Common Lisp way to find the contents of a directory. 

fs:expunge-d1rectory //e5;)^c &key {errori) 

Expunges the directory specified in fikspec, that is, permanently eliminates any deleted 
files in that directory. If error is nil, there is no error if the directory does not exist. 

Note that not all file systems support this fijnction. To find out whether a particular one 
does, send tlie :undeletable-p operation to a patliname. If it returns t, the file system of 
that pathname supports undeletion (and therefore expunging). 

fs:create-d1 rectory fikspec &key {errorX) 

Creates tlie directory specified in fikspec. If error is nil, there is no error if the directory 
cannot be created; instead an error string is returned. Not all file servers support creation 
of directories. 

fs: remote- con nect //f5p^c &key {errori) access 

Performs the TOPS-20 "connect" or "access" ftmction, or their equivalents, in a remote 
file server. Access is done if access is non-nil; otherwise, connect is done. 
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Iho conned operation gninis you iiill access to the specified directory. The access 
operation grants yon \vhate\er access to all files and directories yon would have if logged 
in on the specified directory. iJoth operations affect access only, since the connected 
directory of ihc remote server is never used by tJie Lisp Machine in choosing which file 
to operate on. 

This fimction may ask you for a password if one is required for the directory you specify. 
If the operation cannot be performed, then if error is nil, an error object is retinned. 

file Properties: 

fs:change -file-properties y/7r error p &rest proper/ ies 

Changes one or more properties of the file Jile. The properties arguments arc alternating 
keywords and values. If an error iKXurs accessing the file or changing the properties, the 
errof-p argument controls what is done; if it is nil. a condition object describing tJic error 
is returned; if it is t a Lisp error is signaled. If no error cKcurs, fs:change-file- 
properties returns t. 

Only some of the properties of a file may be changed; for instance, its creation date or 
its autlior. 1 exactly which properties may be changed depends on the host file system; a 
list of tlie changeable property names is Uic isettable- properties property of tJic file 
system as a whole, returned by fs:directory-list as explained above. 

fs:f lie-properties file &optional (error^pi) 

Returns a disembodied property list for a single file (compare this to fs:directory-list). 
Lhe car of tlic returned list is tlie trucname of tlie file and the cdr is an alternating list of 
indicators and values, lhe error^p argument is tlic same as in fs:change- file -properties. 

Filename Completion: 

fs: complete- pathname defaults string type version &rest options 

string is a partially-specified file name. (Presumably it was typed in by a user and 
terminated with tlie Altmode key or tlie End key to request completion.) fsxomplete- 
pathname looks in tlic file system on tlic appropriate host and returns a new, possibly 
more specific string. Any unambiguous abbreviations are expanded out in a host- 
dependent fashion. 

defaults, type, and version are tlic arguments to be given to fs:merge-pathname- 
defaults (see page 558) when the user's input is eventually parsed and defaulted. 

options are keywords (without following values) diat control how the completion is 
performed. The following option keywords arc allowed: 

:deleted Looks for files which have been deleted but not yet expunged. 

:read or :in ITic file is going to be read. This is the default. 

iprint or :write or :out 

ITie file is going to be written (i.e. a new version is going to be created). 
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:old Looks only for Dies thai already exist. Tiiis is the delaiilt. 

:new-ok Allows either a file that already exists or a file that does not yet exist. An 

example of the use of this is Ihe C-X C-F (Find File) command in the 
editor. 

The first value retin-ned is always a string containing a file name, either the original string 
or a new, more specific string. The second value returned indicates the success or failure 
of the completion, it is nil if an error occurred. One possible error is that the file is on 
a file system that does not support completion, in which case the original string is 
returned unchanged. Other possible second values are :old, which means that the string 
completed to the name of a file that exists, :new, which means that the siring completed 
to the name of a file that could be created, and nil again, which means that there is no 
possible completion. 

lialance !3irectorics: 

fs:balanco-d1rector1es filcspec I filcspccl &rcst options 

fs:balance-directories is a fimction for maintaining multiple copies of a directory. Often 
it is useful to maintain copies of your files on more than one machine; tJiis function 
provides a simple way of keeping Uiose copies up to date. 

The function first pnrscs filespec J , filling in missing components with wildcards (except for 
tlie version, which is :newest). Then filcspec2 is parsed with filcspec I as the default. The 
resulting patlinames are used to generate directory lists using fs:directory-IJst. Note that 
the resulting directory lists need not be entire directories; any subset of a directory that 
fs:directory-list can produce will do. 

First tlic directory lists are matched up on the basis of file name and type. All of the 
files in either directory list which have both the same name and the same type are 
grouped together. 

The directory lists are next analyzed to determine if the directories are consistent, meaning 
that two files with tlie same name and type have equal creation-dates when their versions 
match, and greater versions have later creation-dates. If any inconsistencies are found, a 
warning message is printed on the console. 

If the version specified for both filcspec 1 and filcspec2 was :nevi/est (the default), tlien the 
newest version of each file in each directory is copied to the other directory if it is not 
already there. The result is tliat each directory has tlie newest copy of every file in either 
of the two directories. 

If one or both of the specified versions is not :newest, then every version that appears in 
one directory list and not in tlie other is copied. 'ITiis has the result that the two 
directories are completely the same. (Note that this is probably not the right tiling to use 
to copy an entire directory. Use copy-file with a wildcard argument instead.) 

The options are keywords arguments which modify the operation. The following options 
are currently defined: 
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:ignore Ihis opiion liikcs one ingiimcnl, which is a lisi of file names lo ignore 

when making the direciory lisls. The dcfaiih value is nil. 

:error This opiion is identical to Ihc :error option to open. 

:query-mode This option takes one argument, which indicates whether or not the user 
should be asked before files are transferred. If the argument is nil, no 
querying is done. If it is :1->2, then only files being tiansferred from 
JilcspccJ [{) filcspccl are queried, while if it is :2->1, then files transferred 
from fih'spccl to JilcspecJ are queried. If the argument is :always, then 
the user is asked about all files. 

:copy-mode This option is identical to the :copy-mode option of copy-file, and is 
used lo control whether files are treated as binary or textual data. 

.direction This opiion specifies transfer of files in one direction only. If the value is 

:1->2 then files arc iransfered only ^wm filcspccl io filcspccl, never in tlic 
other direction. If tlie value is :2->1 then files are transferred only from 
filcspcc2 U) filcspccJ . nil, tlie default, means transfer in either direction as 
appropriate. 



25.7 Errors in Accessing Files 

fs:f He-error (error) 

This flavor is tlic basis for all errors signaled by the file system. 



Condition Flavor 



It defines two special operations, :pathname and :operation. Usually, these return the 
padinamc of the file being operated on, and the operation used. This operation was 
perfonncd either on the paUinamc object itself, or on a stream. 

It defines prompting for the proceed types :retry-file-operation and :new-pathname, 
both of which are provided for many file errors. :retry-flle-operation tries tlie operation 
again exacdy as it was requested by die program; :new- pathname expects on argument, 
a pathname, and tries the same operation on this pathname instead of the original one. 

fs:f ne-operat1on-fa1lure (fs:file-error) Condition 

This condition name signifies a problem with the file operation requested. It is an 
alternative to fs:file- request-failure (page 609), which means that the file system was 
unable to consider the operation properly. 

All the following conditions in this section arc always accompanied by fs:file-operation- 
failure, fs:file -error, and error, so they will not be mentioned. 



fs : f ne-open-fop-output 

ITic request cannot be performed because the file is open for output. 



Condition 
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fs: file locked Condi Hon 

The file cannot be accessed because it is already being accessed. Just which kinds of 
sinuilianeous access arc allowed depends on the file system. 

fs;c1rcular-Hnk ( omiiiion 

A link could not be opened because it pointed, directly or indirectly through other links, 
to itself, hi fact, some systems report this condition whenever a chain of links exceeds a 
fixed length. 

fs: 1nval1d-byte-s1ze Condition 

In open, the specified byte size was not valid for the particular file server or file. 

f s : no-more-room Condition 

Processing a request requires resources not available, such as space in a directory, or free 
disk bl{K;ks. 

fs:f Hepos-out-of-range Condition 

The :set-pointer operation was used with a pointer value outside tlic bounds of the file. 

fs: not-available Condition 

A requested pack, file, etc. exists but is currently off line or not available to users. 

fs:f lie-lookup- err or Condition 

This condition name categorizes all sorts of failure to find a specified file, for any 
operation. 

fs:dev1ce-not-found (fs:file-lookup-error) Condition 

The specified device docs not exist. 

fs:d1rectory-not-found (fs:file-lookup-error) Condition 

The specified directory docs not exist. 

fsifHe-not-found (fs:file- lookup-error) Condition 

There is no file with the specified name, type and version. This implies that the device 
and directory do exist, or one of the errors described above would have been signaled. 

fs:mult1ple-f lle-not-found (fs:file- lookup -error) Condition 

There is no file with the specified name and any of the specified types, in with -open - 
file-search. Three special operations are defined: 

:operatlon Returns tlie function which used with -open -file-search, such as load. 

pathname The base pathname used. 

:path names A list of all the patlinames that were looked for. 

fs: link- target-not-found (fs.file- lookup -error) Condition 

ITie file specified was a link, but tlie link's target filename fails to be found. 
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fs: access-error Condition 

The opciiUiDii is possible, but ihc file server is insubordinate and refuses lo obey you. 

fs: Incorrect-access-to-fHe (access-error). Condiiion 

fs: incorrect-access-to-d1 rectory (access -error). Condition 

The file server refuses to obey you beeause of protection attached lo the file (or, the 

directory). 

fs: Invalid-wildcard Condition 

A pathname had a wildcard in a place where the particular file server does not support 
them. Such pathnames are not created by pathname parsing, but they can be created 
with the :new-pathname operation. 

fs:w11dcard- not- all owed Condition 

A pathname with a wildcard was used in an operation that does not support it. For 
example, opening a file with a wildcard in its name. 

fs:wrong-k1nd-of-fne Condition 

An operation was done on the wrong kind of file. If files and directories share one name 
space and it is an error to open a directory, tlic error possesses tliis condition name. 

fs: creation-failure Condifion 

An attempt to create a file or directory failed for a reason specifically connected with 
creation. 

fs:f11e-already-ex1sts (fs.creation- failure) Condiiion 

The file or directory to be created already exists. 

fs: super lor- not-directory (fsxreation -failure fsiwrong-kind-of-file) Condition 

In file systems where directories and files share one name space, this error results from an 
attempt to create a file using a filename specifying a directory whose name exists in the 
file system but is not a directory. 

fs:delete- failure Condition 

A file to be deleted exists, but for some reason cannot be deleted. 

fs:dlpectopy-not-empty (fs:delete- failure) Condition 

A file could not be deleted because it is a directory and has files in it. 

fs:dont-delete-f lag-set (fs:delete-fallure) Condition 

A file could not be deleted because its "don't delete" flag is set. 

fs:rename-fa11ur6 Condition 

A file to be renamed exists, but the renaming could not be done. The :new-pathname 
operation on the condition instance returns the specified new pathname, which may be a 
pathname or a string. 
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f s : rename-to-ex1st1ng f He (fs:rename- failure) (oihiiiion 

Reniiniing caiinol be tioire because llicre is already a file with the specified new name. 

fs:Pename-across-di rectories (fs:rename-failure) Condiihm 

Renaming cannot be done because the new pathname contains a dilTerent device or 
directory from the one the file is on. This may not always be an error — some file systems 
support it in certain cases — but when it is an error, it has this condition name. 

f s : unknown-property (fsxhange-property-failure) Condition 

A property name specified in a :change- properties operation is not supported by the file 
server. (Some file servers support only a fixed set of property names.) ihe :property 
operation on the condition instance returns the problematical property name. 

fs: invalid-property-value (fsxhange-property-failure) Condition 

In a :change- properties operation, some property was given a value that is not valid for 
it. The property operation on the condition instance returns the property name, and the 
lvalue operation returns tlic specified value. 

fs: invalid-propepty-name (fsxhange-property-failure) Condition 

In a xhange- properties operation, a syntactically invalid property name was specified. 
This may be because it is too long to be stored. The :property operation on the 
condition instance returns the property name. 

25.8 File Servers 

Files on remote file servers arc accessed using file seners over tlie Chaosnet. Normally 
connections to servers arc established automatically when you try to use them, but tliere arc a few 
ways you can interact with tliem explicitly. 

When characters are written to a file server computer tliat nonnally uses tlie ASCII character 
set to store text, Lisp Machine characters are mapped into an encoding that is reasonably close to 
an ASCII transliteration of tlie text. When a file is written, the characters are converted into this 
encoding; the inverse transformation is done when a file is read back. No information is lost. 
Note that the lengtli of a file, in characters, is not the same measured in original Lisp Machine 
characters as it is measured in tlie encoded ASCII characters. In the currently implemented 
ASCII file servers, the following encoding is used. All printing characters and any characters not 
mentioned explicitly here are represented as tlicmselves. Codes 010 (lambda), Oil (gamma), 012 
(delta), 014 (plus-minus), 015 (circle-plus), 177 (integral), 200 through 207 inclusive, 213 (Delete), 
and 216 and anything higher, are preceded by a 177; that is, 177 is used as a quoting character 
for these codes. Codes 210 (Overstrike), 211 (Tab), 212 (Line), and 214 (Page), arc converted 
to their ASCII cognates, namely 010 (backspace). Oil (horizontal tab), 012 (line feed), and 014 
(form feed) respectively. Code 215 (Return) is converted into 015 (carriage return) followed by 
012 (line feed). Code 377 is ignored completely, and so cannot be stored in files. 

When a file server is first created for you on a particular host, you must tell tlie server how 
to log in on that host. This involves specifying a username, and, if the obstructionists are in 
control of your site, a password, l^he Lisp Machine prompts you for these on tlie terminal when 
they are needed. 
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logging in i\ (lie server is nol ihe same ihing iis logging in on ihe lisp Machine (sec login, 
jiage 801), The latter identifies you as a user in general and involves specifying one host, your 
login host. The former identifies you to a particular file server host and must be done for each 
host on which you access files. However, logging in on the Lisp Machine docs specify tlic 
username for your login host and logs in a file server ihcrc. 

The lisp Machine uses your username (or ihc part that follows the last period) as a first 
guess for your password (this happens to take no extra time). If that does not work, you arc 
asked to tyjic a password, or else a username and a password, on the keyboard, "^'ou do not 
have to give the same user name that you are logged in as. since you may have or use different 
user names on difierent machines. 

Once a password is recorded for one host, the system uses that password as the guess if you 
connect to a file server on another host. 

fs:user-unames Variable 

This is an alisi matching host names with the uscrnamcs you have specified on those 
hosts. P.ach clement is the cons of a host object and tlic username, as a string. 

For hosts mnning ITS, tJic symbol fs:its is used instead of a host object. This is because 
every user has tlic same username on all I'l'S hosts. 

fs:user-host-password-al1st Variable 

Once you have specified a password for a given username and host, it is remembered for 
tlic duration of the session in this variable. The value is a list of elements, each of the 
form 

( ( username hostname) password) 
All ilirce data arc strings. 

The remembered passwords are used if more than one file server is needed on the same host, 
or if tlie connection is broken and a new file server needs to be created. 

If you are very scared of your password being known, you can turn oif the recording by 
setting this variable: 

fsirecord-passwords-flag Variable 

Passwords are recorded when typed in if this variable is non-nil. 

You should set the variable at the front of your init file, and also set fs:user- host- 
password -alist to nil, since it will already have recorded your password when you logged in. 

If you do not use a file server for a period of time, it is killed to save resources on the 
server host. 

fs:host-un1t-l1fet1in8 Variable 

lliis is the length of time after which an idle file server connection should be closed, in 
6t)ths of a second. Hie default is 20 minutes. 
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Sonic hosls hiive a caslc system in wiiich all users are ni)l equal. Ii is sonieliincs necessary to 
enable one's privileges in order to exercise them. This is done with these functions: 

fs:enable-capabnit1es host &rest capabiliiies 

i^nables the named cajxibilities on file servers for the specified host, cupahili/ics is a list of 
strings, whose meanings depend on the particular file system that is available on Jiost. if 
capabiliiies is nil, a default list of capabilities is enabled; the default is also dependent on 
the operating system type. 

fs:cHsable-capabnit1es hosi &rest capabiliiies 

Disables the named capabilities on file servers for the specified host, capabiliiies is a list 
of strings, whose meanings depend on the particular file system that is a\ailablc on liosl. 
If capabiliiies is nil, a default list of capabilities is disabled; the default is also dependent 
on the operating system type. 

The PHHK utility has a mode that displays the sUUus of all your file connections, and of the 
hosi unit data structures that record them. Clicking on a connection with the mouse gets a menu 
of operations, of which the most interesting is reset. Resetting a host unit may be useful if die 
connection becomes hung. 

25.8.1 Errors in Communication with File Servers 

fsiflle-request-fallure (fs.file-error error) Condition 

This condition name categorizes errors that prevent the file system from processing the 
request made by the program. 

Tlic following condition names arc always accompanied by the more general classifications 
fs:file- request-failure, fs:file-error, and error. 

fsrdata-errop Condition 

This condition signifies inconsistent data found in the file system, indicating a failure in 
the file system software or hardware. 

fs:host-not-avai1ab1e Condition 

This condition signifies that the file server host is up, but refusing connections for file 
servers. 

fs:network-1ossage Condition 

This condition signifies certain problems in the use of the Chaosnet by a file server, such 
as failure to open a data connection when it is expected. 

fs:not-enough-resources Condition 

1 his condition signifies a shortage of resources needed to consider processing a request, as 
opposed to resources used up by the request itself, l^his may include running out of 
network connections or job slots on die server host. It does not include running out of 
space in a directory or running out of disk space, because these are resources whose 
requirements come from processing the request. 
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fs:unknown-operat1on Comfiiion 

This condition signifies that the piuticiilar file system fails to implement a standardly 
defined operation; such as, expunging or undeletion on I'I'S. 
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